SID+Midi Music Player docs (2)
------------------------------

How to setup a song:
--------------------

Most people will find a setup they're happy with for writing music and from then on can 
skip the first set of steps when they want to write a new song.

1) Decide what sort of editor setup you'd like to use.  I would suggest the easiest is 
   probably using Sid Wizard's 3SID mode as this gives you all 9 channels in one file.

2) Open midiwrapper.asm in a text editor and look for a line called 'startsong'.  
   It'll look like this:

   startsong
 	   lda #$02 ; Number of music players used.
     
   Change that #$02 to the number of music players you'll be using.  As an example: if 
   you decide to use Sid Wizard as above you'd only have 1 player, so change it to #$01

2) At the end of that midiwrapper file are the incbin lines where you put in the name 
   of your compiled song(s) and their memory addresses.  Look for the 'org $1000' line 
   which is where I've put the first song in each folder. ($1000 is usually the default 
   memory address editors will export to)

   org $1000-$02
   .incbin piano-1000.prg

   Change the filename after the .incbin to your exported song name.  If you have multiple 
   songs add more org lines with their memory addresses set accordingly.

   The -$02 on the end tells DASM to place it 2 bytes earlier in memory to skip the program's 
   header file.  Most music editors allow you to save in the following formats, any of which 
   you can use as follows:

   1) PRG - The default C64 format with a 2 byte address header on the front. 
            (put -$02 on the end of your org address)
   2) BIN - A raw data file without the header. (you only need the load address. eg: org $1000)
   3) SID - The standard SID format. (put -$7c on the end of your org address to skip the SID header)

   Memory area from $1000-$bfff is free for your songs.

3) Now we need to tell the driver how our song(s) work, so load up mididata.asm.  The first thing 
   we need to do is tell it the memory and play addresses so it can play the songs back to us.

   a) Under player_patchsid put in the first two digits of your songs org address. 
      (eg: if it's $1000, put in $10)

   b) Under player_playhi put in the first two digits of the songs play address, this is usually 
      the same as the load address.

   c) Under player_playlo put the last two digits of the songs play address, this is usually 
      $03 though some use $06

4) Your song players get patched to send the sid registers to a buffer area, this is under patch_memorylo
   Depending on how many players you're using you'll need to change the table to read as follows:

   1 player  - .byte $00,$00,$00,$00
   2 players - .byte $00,$00,$40,$60
   3 players - .byte $00,$20,$40,$60
 
5) If you're using different editor songs together (such as a Goat Tracker and Sid Wizard song) you may 
   find they don't start at exactly the same time.  This is because internally some editors write to the
   registers a few frames after they process them.  To get around this you can skip a set amount of frames
   before normal playback to get them to play in time.

   Under player_startdelay change the $ff of your numbered player to a different value.  For GoatTracker2
   $03 got things in sync for the demo track, though the root frame tempo of your song is probably a factor
   too.  You may find you need to skip more than one of your players to get them in sync together.  It's best
   to experiment with different values. 


Making midi instruments
-----------------------

   Now we can edit instruments, if you're happy with your editor setup this is the only bit you probably
   need to change when making new songs. 

   In mididata.asm you'll spot a bunch of tables labelled patchdatatrack1, patchdatatrack2 etc.  These are
   the instrument patches for the SID channels in your source songs.

   Each sid channel can use up to 8 different patches, depending on which waveform is playing. ($10-$80)

   These are listed one after the other and have 8 bytes of data.  As an example:
         
         1              2       3            4         5          6            7       8
         midi channel   patch   fixed note   susvel    reldelay   moddelay     modval  transpose
         0 ,            0 ,     128 ,        255  ,    255 ,      255   ,      0 ,     0

   The bytes describe:

   1) Midi channel to use. (values 00-15 = midi channels 1-16)  
      On the first 3 channels if this value is 128 the midi send is muted so you can use the sid voice
      on it's own with that waveform.

   2) Patch to use (0-127)

   3) Play a fixed note on this patch? (128 = no, play the sid channel's note. 0-127 = yes, play this fixed note)

   4) Take Velocity value of note from the sid channel's sustain value?
      (255 = Yes, convert sustain to midi velocity. 0-127 = No, use this fixed midi velocity)

   5) Take Note Off delay from the sid channel's release value? 
      (255 = Yes, 0-127 = No, use this fixed delay value)
      
      Note off delay is how many frames it waits after the sid gate off happens before sending it
      to the midi device.  This tries to simulate the release time of a sid instrument so it feels 
      more natural working with midi in a tracker.

   6) Mod Wheel (vibrato) delay? 
      (255 = don't use modulation, 0-127 frames to wait before modulation is active)

   7) Modulation (vibrato) amount (0-127)

   8) Midi note transpose from SID channel root note (only upwards, eg: 12 = an octave above)


   Allowing the SID chip values to control velocity and release means you can make more natural sounding
   songs by using an FX command to change those values in your editor.  Most modern editors have a 
   'Change Sustain/Release value' fx.

   For some example instrument settings I suggest looking through the demo songs with the source file
   open in an editor to see how they match up.

   If your device is General Midi compliant the standard drum track (10) will be available, though obviously
   it's 9 in this driver.  You can use the normal key range in your sid editor to play the different parts
   or set a fixed value for certain patches to only play one drum type. 

   The waveform instruments $30, $60 and $70 are more audible on 8580 soundchips, I've included them more to
   give each midi channel more choices than for their SID tonal quality.


Changing the splash screen text
-------------------------------

At the end of midiwrapper.asm there are 3 labels named song_name, song_author and song_released.  These are
the text lines displayed on the splash screen.  Change these to personalise your song, each line must end
with a $00 byte.
